<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Arrays</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>

<body>
<h1>Arrays</h1>

<h2>Associative Arrays <span class="ver">[AHK_L 31+]</span></h2>
<p>Self-contained associative arrays can be created by calling <a href="../Objects.htm#Arrays">Object()</a>. For example:</p>
<pre><em>; Create the array, initially empty:</em>
Array := Object()

<em>; Write to the array:</em>
Loop, Read, C:\Guest List.txt <em>; This loop retrieves each line from the file, one at a time.</em>
{
    Array.Insert(A_LoopReadLine) <em>; Append this line to the array.</em>
}

<em>; Read from the array:
; Loop % Array.MaxIndex()   ; More traditional approach.</em>
for index, element in Array <em>; Recommended approach in most cases.</em>
{
    <em>; Using "Loop", indices must be consecutive numbers from 1 to the number
    ; of elements in the array (or they must be calculated within the loop).
    ; MsgBox % "Element number " . A_Index . " is " . Array[A_Index]
    
    ; Using "for", both the index (or "key") and its associated value
    ; are provided, and the index can be *any* value of your choosing.</em>
    MsgBox % "Element number " . index . " is " . element
}</pre>
<p>This shows only a small subset of the <a href="../objects/Object.htm">functionality</a> provided by <a href="../Objects.htm">objects</a>. Items can be set, retrieved, inserted, removed and enumerated. Strings and objects can be used as keys in addition to numbers. Objects can be stored as values in other objects and passed as function parameters or return values. Objects can also be <a href="../Objects.htm#Custom_Objects">extended</a> with new functionality.</p>
<p>Though Insert() and enumerators have their uses, some users might find it easier to use the more traditional approach:</p>
<pre>
  <em>; Each array must be initialized before use:</em>
  Array := Object()

<em>; Array%j% := A_LoopField</em>
  Array[j] := A_LoopField

<em>; Array%j%_%k% := A_LoopReadLine</em>
  Array[j, k] := A_LoopReadLine

  ArrayCount := 0                        
  Loop, Read, C:\Guest List.txt
  {
      ArrayCount += 1
    <em>; Array%ArrayCount% := A_LoopReadLine</em>
      Array[ArrayCount] := A_LoopReadLine
  }

  Loop %ArrayCount%
  {
    <em>; element := Array%A_Index%</em>
      element := Array[A_Index]
    <em>; MsgBox % "Element number " . A_Index . " is " . Array%A_Index%</em>
      MsgBox % "Element number " . A_Index . " is " . Array[A_Index]
  }
</pre>
<p><i>ArrayCount</i> is left as a variable for convenience, but can be stored in the array itself with <code>Array.Count := <i>n</i></code> or it can be removed and <code>Array.<a href="../objects/Object.htm#MinMaxIndex">_MaxIndex()</a></code> used in its place. If a starting index other than 1 is desired, <code>Array.<a href="../objects/Object.htm#MinMaxIndex">_MinIndex()</a></code> can also be used.</p>

<h2 id="pseudo">Pseudo-Arrays</h2>
<p>Pseudo-arrays are mostly conceptual: Each array is really just a collection of sequentially numbered <a href="../Variables.htm">variables</a> or <a href="../Functions.htm">functions</a>, each one being perceived as an <em>element</em> of the array. AutoHotkey does not link these elements together in any way.</p>
<p>In addition to array-creating commands like <a href="../commands/StringSplit.htm">StringSplit</a> and &quot;<a href="../commands/WinGet.htm">WinGet List</a>&quot;, any command that accepts an OutputVar or that assigns a value to a variable can be used to create an array. The simplest example is the <a href="../commands/SetExpression.htm">assignment operator (:=)</a>, as shown below:</p>
<pre>Array%j% := A_LoopField</pre>
<p>Multidimensional arrays are possible by using a separator character of your choice between the indices. For example:</p>
<pre>Array%j%_%k% := A_LoopReadLine</pre>
<br>
<p>The following example demonstrates how to create and access an array, in this case a series of names retrieved from a text file:</p>
<pre><em><strong>; Write to the array:</strong></em>
ArrayCount = 0
Loop, Read, C:\Guest List.txt   <em>; This loop retrieves each line from the file, one at a time.</em>
{
    ArrayCount += 1  <em>; Keep track of how many items are in the array.</em>
    Array%ArrayCount% := A_LoopReadLine  <em>; Store this line in the next array element.</em>
}

<em><strong>; Read from the array:</strong></em>
Loop %ArrayCount%
{
    <em>; The following line uses the := operator to retrieve an array element:</em>
    element := Array%A_Index%  <em>; <a href="../Variables.htm#Index">A_Index</a> is a built-in variable.</em>
    <em>; Alternatively, you could use the &quot;% &quot; prefix to make MsgBox or some other command <a href="../Variables.htm#Expressions">expression-capable</a>:</em>
    MsgBox % &quot;Element number &quot; . A_Index . &quot; is &quot; . Array%A_Index%
}</pre>
<p>A concept related to arrays is the use of <a href="../commands/NumPut.htm">NumPut()</a> and <a href="../commands/NumGet.htm">NumGet()</a> to store/retrieve a collection of numbers in binary format. This might be helpful in cases where performance and/or memory conservation are important.</p>

</body>
</html>
